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/services/access.py

@@ -0,0 +1,95 @@
+"""Paid-tier access checks.
+
+Two sources can grant paid access:
+
+1. ``user.tier in {"paid", "enterprise"}`` — set by Paddle webhook in
+   Phase D.3 once a subscription is active.
+2. ``user.credit_until > now()`` — non-subscription credit. Currently
+   populated by the admin CLI (`python -m app.cli grant-credit`) and, in
+   D.3, by the referral-conversion path (3 months at 50% off).
+
+Either is sufficient. We use a single ``paid_status`` function so the
+Settings page can show *why* a user has paid access ("paid subscription"
+vs "credit, 47 days left") without duplicating the rules.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from fastapi import Depends, HTTPException, status
+
+from app.auth import CurrentUser, require_auth
+from app.models import User
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+@dataclass(frozen=True)
+class PaidStatus:
+    """Snapshot of paid-tier status for one user."""
+    active: bool
+    source: str | None              # "tier" | "credit" | None
+    expires_at: datetime | None     # only meaningful when source == "credit"
+    days_remaining: int | None      # only meaningful when source == "credit"
+
+
+def _aware(dt: datetime | None) -> datetime | None:
+    """MariaDB round-trips DateTime(timezone=True) as a naive UTC value
+    via aiomysql. Normalise to tz-aware so comparisons against utcnow()
+    never raise."""
+    if dt is None:
+        return None
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def paid_status(user: User | None) -> PaidStatus:
+    """Compute paid-tier status for a User row. ``user=None`` (anonymous
+    or admin bearer-token) returns inactive — callers should special-case
+    admin separately via ``is_paid_active``."""
+    if user is None:
+        return PaidStatus(False, None, None, None)
+    if user.tier in ("paid", "enterprise"):
+        return PaidStatus(True, "tier", None, None)
+    cu = _aware(getattr(user, "credit_until", None))
+    if cu is not None and cu > _utcnow():
+        days = max(0, (cu - _utcnow()).days)
+        return PaidStatus(True, "credit", cu, days)
+    return PaidStatus(False, None, None, None)
+
+
+def is_paid_active(principal: CurrentUser | User | None) -> bool:
+    """True if the principal has paid-tier access right now. Admin
+    bearer-token (``CurrentUser.is_admin=True``) always passes."""
+    if principal is None:
+        return False
+    if isinstance(principal, CurrentUser):
+        if principal.is_admin:
+            return True
+        return paid_status(principal.user).active
+    return paid_status(principal).active
+
+
+async def require_paid(
+    principal: CurrentUser = Depends(require_auth),
+) -> CurrentUser:
+    """FastAPI dependency for paid-only endpoints. Returns the principal
+    on success; raises 402 Payment Required otherwise.
+
+    402 is the semantically-correct code for "auth succeeded but plan
+    insufficient" — distinct from 401 (not authenticated) and 403
+    (authenticated but forbidden by ACL). Frontends key off it to show
+    the upgrade prompt rather than redirecting to /login."""
+    if is_paid_active(principal):
+        return principal
+    raise HTTPException(
+        status_code=status.HTTP_402_PAYMENT_REQUIRED,
+        detail={
+            "code": "paid_required",
+            "message": "This feature requires an active paid plan or credit.",
+        },
+    )