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/auth.py

@@ -87,15 +87,26 @@ def _pending_serializer() -> URLSafeTimedSerializer:
     return URLSafeTimedSerializer(secret, salt="cassandra-pending-v1")
 
 
-def sign_pending(email: str, user_id: int) -> str:
-    return _pending_serializer().dumps({"email": email, "uid": int(user_id)})
+def sign_pending(email: str, user_id: int, ref: str | None = None) -> str:
+    """Signed payload for the pending-verify cookie. Carries the email
+    + user_id under verification, and optionally a referral code captured
+    at signup (so it survives the GET → POST → /verify hop)."""
+    payload: dict = {"email": email, "uid": int(user_id)}
+    if ref:
+        payload["ref"] = ref
+    return _pending_serializer().dumps(payload)
 
 
 def verify_pending(cookie: str) -> dict | None:
-    """Returns {"email": str, "uid": int} or None if signature/expiry bad."""
+    """Returns {"email": str, "uid": int, "ref": str|None} or None if
+    signature/expiry bad."""
     try:
         data = _pending_serializer().loads(cookie, max_age=PENDING_TTL_SECONDS)
-        return {"email": str(data["email"]), "uid": int(data["uid"])}
+        return {
+            "email": str(data["email"]),
+            "uid": int(data["uid"]),
+            "ref": data.get("ref"),
+        }
     except (BadSignature, SignatureExpired, KeyError, TypeError, ValueError):
         return None