feat(story-5.2): add Stripe subscription checkout with session verification

Add POST /api/v1/stripe/create-subscription-checkout endpoint with
get_or_create_stripe_customer (SELECT FOR UPDATE), plan_id→price_id
mapping from env vars, active subscription guard (409), and
session_id in success URL. Add GET /verify-checkout-session endpoint
for server-side payment verification. Add /subscription-success
frontend page with loading/verified/failed states.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

surfsense_backend/app/schemas/stripe.py

@@ -1,13 +1,21 @@
-"""Schemas for Stripe-backed page purchases."""
+"""Schemas for Stripe-backed page purchases and subscriptions."""
 
 import uuid
 from datetime import datetime
+from enum import Enum
 
 from pydantic import BaseModel, ConfigDict, Field
 
 from app.db import PagePurchaseStatus
 
 
+class PlanId(str, Enum):
+    """Supported subscription plan identifiers."""
+
+    pro_monthly = "pro_monthly"
+    pro_yearly = "pro_yearly"
+
+
 class CreateCheckoutSessionRequest(BaseModel):
     """Request body for creating a page-purchase checkout session."""
 
@@ -15,6 +23,18 @@ class CreateCheckoutSessionRequest(BaseModel):
     search_space_id: int = Field(ge=1)
 
 
+class CreateSubscriptionCheckoutRequest(BaseModel):
+    """Request body for creating a subscription checkout session."""
+
+    plan_id: PlanId
+
+
+class CreateSubscriptionCheckoutResponse(BaseModel):
+    """Response containing the Stripe-hosted subscription checkout URL."""
+
+    checkout_url: str
+
+
 class CreateCheckoutSessionResponse(BaseModel):
     """Response containing the Stripe-hosted checkout URL."""