[BE] Implement Referral Bonus Tracking and Reward Distribution

[Hahfyeex]

Type: BE
Component: backend/src/routes

Context

The frontend referral link system tracks referral codes on first bet placement. The backend needs to process these referral codes, validate them, attribute the referred bet to the correct referrer, and distribute referral bonuses. Without the backend implementation, referral codes are collected but never acted upon.

Implementation Guide

1. Create a referrals table: id, referrer_wallet, referred_wallet, first_bet_id, bonus_amount, bonus_paid, created_at.
2. In POST /api/bets, if a referral_code is present in the request body, look up the referrer wallet by hashing the code.
3. Check that the referred wallet has not previously placed a bet (first bet only). If not first bet, ignore the referral code.
4. Insert a referrals record linking the referrer and referred wallets.
5. Add a background job that runs daily and distributes pending referral bonuses: transfer 1 XLM (configurable via REFERRAL_BONUS_XLM env var) to each referrer for each new referred first bet.

Guidelines

• Auth Enforcement: referral bonus distribution requires admin JWT or runs as a system job.
• Key requirement: Referral Code Validation / First Bet Check / Referrals Table / Daily Bonus Distribution / Configurable Bonus Amount.

Definition of Done

• Referral code is correctly attributed to the referrer on first bet placement.
• Subsequent bets from the same referred wallet do not create additional referral records.
• Daily bonus distribution job correctly identifies and pays pending bonuses.
• REFERRAL_BONUS_XLM is configurable via environment variable.
• Unit tests cover first bet attribution, duplicate prevention, and bonus calculation.
• Test coverage > 95%.

PR and Checkout

git checkout -b feat/referral-bonus-backend
git add .
git commit -m "feat: implement referral bonus tracking and daily reward distribution"
git push origin feat/referral-bonus-backend

Open a PR against main and include the issue number in the PR description.