phase D milestones 1+2: referral system + paid-access gate

Lays the billing-prep spine before Paddle lands in D.3.

D.1 — referrals
- users.referral_code: unique 8-char URL-safe code (alphabet excludes the
  ambiguous 0/O/1/I/L). Generated lazily on first /settings hit so existing
  accounts pick one up without a backfill migration.
- users.referred_by_user_id + new referrals audit table (referrer,
  referred, created_at, converted_at, credited_at). converted_at /
  credited_at stay null until D.3 fills them via the Paddle webhook.
- POST /login accepts ?ref=<code>; the code rides on the signed
  pending-verify cookie so it survives the GET → POST → /verify hop.
- /settings page: email, tier badge, referral code chip + invite link
  with one-click copy, pending/converted/active-credits stats grid.
  Settings nav link added to the top bar.

Reward shape: when the referred user makes their first paid Paddle
subscription, both they and the referrer get 50% off for 3 months.
(D.3 wires the actual credit application via the Paddle webhook.)

D.2 — paid-access gate
- users.credit_until: timestamp until which a free-tier account has
  paid-tier access. Null = no credit. Populated by admin CLI now and the
  D.3 webhook later.
- app.services.access exposes paid_status(user) → PaidStatus dataclass
  (active / source / expires_at / days_remaining), is_paid_active() with
  admin-bearer-token bypass, and a require_paid FastAPI dependency that
  raises 402 Payment Required for free-tier callers.
- POST /api/analyze (portfolio AI commentary) gated behind require_paid.
- Settings page surfaces credit window when active ("free · credit · N
  day(s) remaining (expires YYYY-MM-DD)") and the upgrade hint when not.
- Admin CLI: python -m app.cli {grant-credit,revoke-credit,show-status}.
  grant-credit is idempotent — extends from max(now, current expiry) so
  re-running the command never erodes an existing grant.

Migrations 0013 (referrals) and 0014 (credit_until). Tests cover the
paid-status truth table, code generation + normalisation, CLI argument
parsing, and the pending-cookie ref roundtrip (29 new tests).

app/routers/auth.py

@@ -36,7 +36,7 @@ from app.config import get_settings
 from app.db import get_session, utcnow
 from app.logging import get_logger
 from app.services.auth_service import AuthError, get_or_create_user, get_user
-from app.services import otp_service
+from app.services import otp_service, referral_service
 from app.services.email_service import EmailSendError, send_otp
 from app.templates_env import templates
 
@@ -67,10 +67,15 @@ def _set_session_cookie(response: RedirectResponse, user_id: int) -> None:
     )
 
 
-def _set_pending_cookie(response: RedirectResponse, email: str, user_id: int) -> None:
+def _set_pending_cookie(
+    response: RedirectResponse,
+    email: str,
+    user_id: int,
+    ref: str | None = None,
+) -> None:
     response.set_cookie(
         key=PENDING_COOKIE_NAME,
-        value=sign_pending(email, user_id),
+        value=sign_pending(email, user_id, ref=ref),
         max_age=PENDING_TTL_SECONDS,
         httponly=True,
         samesite="lax",
@@ -101,10 +106,29 @@ async def _issue_and_send_otp(session: AsyncSession, email: str) -> bool:
 
 
 @router.get("/login", response_class=HTMLResponse)
-async def login_page(request: Request, next: str | None = None, error: str | None = None):
+async def login_page(
+    request: Request,
+    next: str | None = None,
+    error: str | None = None,
+    ref: str | None = None,
+    session: AsyncSession = Depends(get_session),
+):
+    # If a valid referral code is supplied, surface a small "invited"
+    # banner. We resolve it server-side so the banner can show the
+    # referrer's actual greeting (and a bad code silently degrades).
+    ref_norm = referral_service.normalise_code(ref) if ref else None
+    referrer = (
+        await referral_service.lookup_referrer(session, ref_norm)
+        if ref_norm else None
+    )
     return templates.TemplateResponse(
         request, "login.html",
-        {"next_path": _safe_next(next), "error": error},
+        {
+            "next_path": _safe_next(next),
+            "error": error,
+            "ref": ref_norm if referrer else None,
+            "referrer_present": referrer is not None,
+        },
     )
 
 
@@ -113,9 +137,24 @@ async def login_submit(
     request: Request,
     email: str = Form(...),
     next: str | None = Form(default=None),
+    ref: str | None = Form(default=None),
     session: AsyncSession = Depends(get_session),
 ):
     s = get_settings()
+    # Look up the referrer up front so a bad code doesn't pollute the
+    # rest of the flow. Self-referral protection lives in
+    # referral_service.link_new_user.
+    ref_norm = referral_service.normalise_code(ref) if ref else None
+    referrer = (
+        await referral_service.lookup_referrer(session, ref_norm)
+        if ref_norm else None
+    )
+
+    # Track whether THIS request creates the user row (i.e. a referral
+    # capture window). Cleanest way: probe for existence first.
+    from app.services.auth_service import get_user_by_email
+    was_new = (await get_user_by_email(session, email)) is None
+
     try:
         user = await get_or_create_user(
             session, email, create_if_missing=s.CASSANDRA_SIGNUP_ENABLED,
@@ -123,10 +162,19 @@ async def login_submit(
     except AuthError as e:
         return templates.TemplateResponse(
             request, "login.html",
-            {"next_path": _safe_next(next), "error": str(e), "email": email},
+            {"next_path": _safe_next(next), "error": str(e), "email": email,
+             "ref": ref_norm if referrer else None,
+             "referrer_present": referrer is not None},
             status_code=400,
         )
 
+    # First-time signup with a valid referrer → persist the linkage now.
+    # We do this BEFORE OTP-verify because the row is already created;
+    # if the user abandons OTP we'll have an orphan link but that's
+    # harmless audit data.
+    if was_new and referrer is not None:
+        await referral_service.link_new_user(session, user, referrer)
+
     # Issue OTP only if cooldown allows; if a fresh one was sent in the
     # last 60s we just reuse the existing one (silently) to avoid
     # spamming the user's inbox on a refreshed form submit.
@@ -135,7 +183,13 @@ async def login_submit(
         await _issue_and_send_otp(session, user.email)
 
     resp = RedirectResponse(url="/verify", status_code=303)
-    _set_pending_cookie(resp, user.email, user.id)
+    # Stash the referral code on the pending cookie too — handy for
+    # showing the "invited" badge on the /verify page so the friend
+    # knows the discount is still tracking.
+    _set_pending_cookie(
+        resp, user.email, user.id,
+        ref=ref_norm if referrer is not None else None,
+    )
     return resp