docs: add comprehensive code comments, update README and TASKS, create training and troubleshooting guides

- Add JSDoc comments to API routes and business logic functions
- Update README.md with Phase 2 status and deployment/production notes
- Enhance TASKS.md with estimated timelines and dependencies
- Create docs/STAFF_TRAINING.md for team onboarding
- Create docs/CLIENT_ONBOARDING.md for customer experience
- Create docs/OPERATIONAL_PROCEDURES.md for daily operations
- Create docs/TROUBLESHOOTING.md for common setup issues
- Fix TypeScript errors in hq/page.tsx

docs/TROUBLESHOOTING.md

@@ -0,0 +1,173 @@
+# Guía de Troubleshooting — SalonOS
+
+Esta guía ayuda a resolver problemas comunes durante el setup y desarrollo de SalonOS.
+
+## Configuración de Entorno
+
+### Supabase Auth Issues
+
+#### Error: "Auth session not found"
+- **Causa**: Variables de entorno de Supabase mal configuradas
+- **Solución**:
+  - Verificar `NEXT_PUBLIC_SUPABASE_URL` y `NEXT_PUBLIC_SUPABASE_ANON_KEY`
+  - Asegurarse que las URLs no tengan trailing slash
+  - Probar conexión: `curl https://your-project.supabase.co/rest/v1/`
+
+#### Error: "RLS policy violation"
+- **Causa**: Políticas de Row Level Security no aplicadas
+- **Solución**:
+  - Ejecutar migraciones: `supabase db push`
+  - Verificar políticas en Supabase Dashboard > Authentication > Policies
+  - Para kioskos: asegurar API key válida en headers `x-kiosk-api-key`
+
+#### Error: "Magic link not received"
+- **Causa**: SMTP no configurado en Supabase
+- **Solución**:
+  - Configurar SMTP en Supabase Dashboard > Authentication > Email Templates
+  - Usar servicio como SendGrid o AWS SES
+  - Probar con email de prueba en dashboard
+
+## Integraciones Externas
+
+### Stripe Webhooks
+
+#### Error: "Webhook signature verification failed"
+- **Causa**: Webhook secret mal configurado
+- **Solución**:
+  - Obtener secret desde Stripe Dashboard > Developers > Webhooks
+  - Configurar `STRIPE_WEBHOOK_SECRET` en variables de entorno
+  - Verificar endpoint URL en Stripe coincida con producción
+
+#### Error: "Payment intent not found"
+- **Causa**: Cliente secret expirado o inválido
+- **Solución**:
+  - Regenerar payment intent en backend
+  - Verificar tiempo de expiración (24h por defecto)
+  - Usar idempotency key para evitar duplicados
+
+#### Error: "Deposit calculation incorrect"
+- **Causa**: Lógica de depósito no actualizada
+- **Solución**:
+  - Verificar regla: MIN(service_price * 0.5, 200)
+  - Probar con diferentes precios de servicio
+  - Revisar logs de webhook para valores
+
+### Google Calendar
+
+#### Error: "Service account authentication failed"
+- **Causa**: Credenciales de Google incorrectas
+- **Solución**:
+  - Descargar JSON de service account desde Google Cloud Console
+  - Configurar `GOOGLE_SERVICE_ACCOUNT_JSON` como string JSON
+  - Verificar permisos: Calendar API enabled, service account tiene acceso al calendar
+
+#### Error: "Calendar sync conflicts"
+- **Causa**: Eventos duplicados o sobrepuestos
+- **Solución**:
+  - Implementar lógica de merge para conflictos
+  - Usar event ID como key para evitar duplicados
+  - Loggear conflictos para resolución manual
+
+## Base de Datos
+
+### Migraciones
+
+#### Error: "Migration failed"
+- **Causa**: Dependencias de migración no resueltas
+- **Solución**:
+  - Ejecutar en orden: `supabase migration up`
+  - Verificar foreign keys existen antes de crear constraints
+  - Backup antes de migrar en producción
+
+#### Error: "Duplicate key value violates unique constraint"
+- **Causa**: Datos existentes violan nueva constraint
+- **Solución**:
+  - Limpiar datos conflictivos antes de migrar
+  - Usar `ON CONFLICT` en inserts
+  - Revisar seeds data
+
+### RPC Functions
+
+#### Error: "Function does not exist"
+- **Causa**: Función no creada en Supabase
+- **Solución**:
+  - Ejecutar SQL de funciones desde migrations
+  - Verificar nombre exacto de función
+  - Probar directamente en Supabase SQL Editor
+
+## Frontend Issues
+
+### Next.js Build
+
+#### Error: "Module not found"
+- **Causa**: Dependencias faltantes
+- **Solución**:
+  - Ejecutar `npm install` o `yarn install`
+  - Verificar package.json versiones compatibles
+  - Limpiar node_modules: `rm -rf node_modules && npm install`
+
+#### Error: "TypeScript errors"
+- **Causa**: Tipos desactualizados
+- **Solución**:
+  - Regenerar types: `supabase gen types typescript --local > lib/db/types.ts`
+  - Verificar imports correctos
+  - Usar `any` temporalmente para debugging
+
+## Kiosko System
+
+#### Error: "Kiosk not authorized"
+- **Causa**: API key inválida o expirada
+- **Solución**:
+  - Generar nueva API key en admin dashboard
+  - Configurar en variables de entorno del kiosko
+  - Verificar headers: `x-kiosk-api-key`
+
+#### Error: "No resources available"
+- **Causa**: Recursos no asignados o bloqueados
+- **Solución**:
+  - Verificar migración de recursos ejecutada
+  - Chequear disponibilidad por horario
+  - Revisar lógica de priority assignment
+
+## Deployment
+
+### Vercel Issues
+
+#### Error: "Build failed"
+- **Causa**: Variables de entorno faltantes
+- **Solución**:
+  - Configurar todas las env vars en Vercel dashboard
+  - Verificar build logs para errores específicos
+  - Usar `--verbose` en build command
+
+#### Error: "Domain configuration failed"
+- **Causa**: Wildcard domains no soportados
+- **Solución**:
+  - Configurar subdominios individuales
+  - Usar proxy reverso para wildcard routing
+  - Verificar DNS settings
+
+## Logs y Debugging
+
+### Verificar Logs
+- **Supabase**: Dashboard > Logs > API/PostgreSQL
+- **Vercel**: Dashboard > Functions > Logs
+- **Stripe**: Dashboard > Developers > Logs
+- **Local**: `npm run dev` con console.log
+
+### Common Debug Steps
+1. Verificar variables de entorno
+2. Probar endpoints con curl/Postman
+3. Revisar network tab en browser dev tools
+4. Chequear logs de errores
+5. Verificar permisos y políticas
+
+## Contacto
+
+Si el problema persiste, documentar:
+- Pasos para reproducir
+- Logs de error completos
+- Configuración del entorno
+- Versiones de dependencias
+
+Crear issue en GitHub con esta información.