feat: implement finalize checkout endpoint and update purchase success handling

- Added a new endpoint `/stripe/finalize-checkout` to synchronously fulfill a checkout session, addressing the webhook-vs-redirect race condition.
- Updated the `PurchaseSuccessPage` component to handle various states of the checkout process, including loading, completed, pending, and failed states.
- Introduced a new response model `FinalizeCheckoutResponse` to provide immediate feedback on the purchase status.
- Enhanced the Stripe API service to include the new finalize checkout functionality.

surfsense_backend/app/schemas/stripe.py

@@ -56,6 +56,26 @@ class StripeWebhookResponse(BaseModel):
     received: bool = True
 
 
+class FinalizeCheckoutResponse(BaseModel):
+    """Response from /stripe/finalize-checkout.
+
+    Returned by the success page so the UI can show the post-purchase
+    balance immediately, even when the Stripe webhook hasn't been
+    delivered yet. ``status`` mirrors the underlying purchase row
+    (``pending`` / ``completed`` / ``failed``); the FE polls this
+    endpoint until it sees ``completed`` or a final ``failed``.
+    """
+
+    purchase_type: str  # "page_packs" | "premium_tokens"
+    status: str  # PagePurchaseStatus / PremiumTokenPurchaseStatus value
+    pages_limit: int | None = None
+    pages_used: int | None = None
+    pages_granted: int | None = None
+    premium_credit_micros_limit: int | None = None
+    premium_credit_micros_used: int | None = None
+    premium_credit_micros_granted: int | None = None
+
+
 class CreateTokenCheckoutSessionRequest(BaseModel):
     """Request body for creating a premium token purchase checkout session."""