docs(auth): update route handler comments for context-aware flow

Updates the documentation comments for the `/request-code` and
`/verify-code` route handlers.

The new comments clearly explain the context-aware behavior driven by
the `is_dashboard_login` request body flag, detailing the different
logic for the user-facing app versus the dashboard.

Author: fulleni

routes/api/v1/auth/request-code.dart

@@ -6,12 +6,14 @@ import 'package:ht_shared/ht_shared.dart'; // For exceptions
 
 /// Handles POST requests to `/api/v1/auth/request-code`.
 ///
-/// Initiates the email sign-in process by requesting a verification code
-/// be sent to the provided email address. It supports a context-aware flow
-/// for dashboard logins by checking for an `is_dashboard_login` flag in the
-/// request body. If this flag is true, the `AuthService` will perform
-/// additional checks to ensure the user exists and has the required
-/// permissions before sending a code.
+/// Initiates an email-based sign-in process. This endpoint is context-aware.
+///
+/// - For the user-facing app, it sends a verification code to the provided
+///   email, supporting both sign-in and sign-up.
+/// - For the dashboard, the request body must include `"is_dashboard_login": true`.
+///   In this mode, it first verifies the user exists and has 'admin' or
+///   'publisher' roles before sending a code, effectively acting as a
+///   login-only gate.
 Future<Response> onRequest(RequestContext context) async {
   // Ensure this is a POST request
   if (context.request.method != HttpMethod.post) {