Enrich full codebase with architectural Arabic docblocks and synchronize database_schema.sql with live database

apps/student_app/lib/presentation/screens/curriculum/curriculum_document_viewer_screen.dart

@@ -1,9 +1,23 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - IN-APP CURRICULUM DOCUMENT & TEXTBOOK READER
+/// ==============================================================================
+/// 
+/// ملف: curriculum_document_viewer_screen.dart
+/// الهدف المعماري:
+/// عارض وقارئ المستندات وأوراق العمل والكتب المدرسية المقررة داخل التطبيق مباشرة:
+/// 1. قراءة سلسة ومريحة للمحتوى دون الحاجة للتحميل والتطبيقات الخارجية.
+/// 2. التحكم اللحظي بحجم الخط (Font Zoom Control +/-).
+/// 3. عرض مهيكل للنتاجات، القواعد الذهبية، الأمثلة الوزارية المحلولة خطوة بخطوة.
+/// 4. تمارين تفاعلية للتقييم الذاتي مع زر لمسي لإظهار وإخفاء الحل النموذجي.
+library;
+
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 import '../../../core/theme/app_colors.dart';
 import '../../../core/utils/saqel_toast.dart';
 import '../../widgets/luxury_widgets.dart';
 
+/// شاشة عارض أوراق العمل والملخصات والكتب الوزارية التفاعلية
 class CurriculumDocumentViewerScreen extends StatefulWidget {
   final String title;
   final String documentType; // 'worksheet', 'summary', 'textbook'

apps/student_app/lib/presentation/screens/curriculum/subject_hub_screen.dart

@@ -1,3 +1,16 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - SUBJECT HUB & MULTI-TEACHER CURRICULUM SCREEN
+/// ==============================================================================
+/// 
+/// ملف: subject_hub_screen.dart
+/// الهدف المعماري:
+/// المركز الشامل للمادة الدراسية (Subject Hub):
+/// 1. فهرسة وحدات ودروس المنهاج الوزاري وشروحات المعلمين والذكاء الاصطناعي.
+/// 2. بطاقة اختيار الشرح متعدد المعلمين (Multi-Teacher & Saqel AI Video Selector Modal).
+/// 3. مركز بنك الأسئلة والامتحانات التكيفية لبدء الاختبارات الشاملة (Adaptive Exams).
+/// 4. تبويب المذكرات وأوراق العمل والكتب المدرسية المقررة للقراءة والتصفح المباشر.
+library;
+
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 import '../../../core/theme/app_colors.dart';
@@ -9,6 +22,7 @@ import '../player/socratic_video_player_screen.dart';
 import '../exams/adaptive_exam_screen.dart';
 import 'curriculum_document_viewer_screen.dart';
 
+/// الشاشة المركزية للمادة الدراسية وبوابات الدروس والامتحانات والمصادر
 class SubjectHubScreen extends StatefulWidget {
   final SubjectModel subject;
 

apps/student_app/lib/presentation/screens/exams/adaptive_exam_screen.dart

@@ -1,3 +1,17 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - ADAPTIVE EXAM SCREEN (CUPERTINO LUXURY UI)
+/// ==============================================================================
+/// 
+/// ملف: adaptive_exam_screen.dart
+/// الهدف المعماري:
+/// شاشة تقديم الامتحانات التكيفية بتصميم أبل كوبرتينو المظلم (Dark OLED Aesthetic):
+/// 1. مؤشر تقدم تفاعلي متزامن مع نسبة الإجابات المكتملة.
+/// 2. مؤقت تنازلي ذكي يتغير لونه إلى الأحمر عند اقتراب انتهاء الوقت.
+/// 3. بطاقات أسئلة لمسية فاخرة مع أزرار اختيار مشعة (Glowing Glassmorphic Radios).
+/// 4. شاشة عرض نتائج متقدمة تحتوي على: نسبة الإتقان، وسام الاجتياز، تقرير التشخيص بالذكاء الاصطناعي،
+///    وسوم نقاط الضعف، ومؤشر الجاهزية لامتحان التوجيهي.
+library;
+
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
@@ -7,6 +21,7 @@ import '../../../core/utils/saqel_toast.dart';
 import '../../../logic/cubits/exam_cubit.dart';
 import '../../widgets/luxury_widgets.dart';
 
+/// الشاشة التكيفية لتقديم الامتحان واستقبال نتائج التصحيح اللحظية
 class AdaptiveExamScreen extends StatelessWidget {
   final int examId;
   final String title;

apps/student_app/lib/presentation/screens/player/socratic_video_player_screen.dart

@@ -1,3 +1,18 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - SOCRATIC VIDEO PLAYER SCREEN
+/// ==============================================================================
+/// 
+/// ملف: socratic_video_player_screen.dart
+/// الهدف المعماري:
+/// مشغل الفيديو السقراطي الذكي والمحمي في تطبيق صَقِل:
+/// 1. تشغيل الفيديو الرقمي وبث HLS عبر مشغل مخصص عالي الأداء.
+/// 2. حماية الملكية الفكرية بعلامة مائية متحركة ديناميكية (Dynamic Anti-Piracy Watermark).
+/// 3. محاذاة نقاط التقدم اللمسية مع نقاط الفحص السقراطي الزمني (Socratic Checkpoints).
+/// 4. تجميد الفيديو وإظهار نافذة الفحص السقراطي عند وصول المؤشر لنقطة الفحص.
+/// 5. تفعيل الإرجاع العلاجي (Rewind Remediation) عند الإجابة الخاطئة لترسيخ الفهم.
+/// 6. إبراز شارة المعلم المختار (شرح الذكاء الاصطناعي أو المعلم المعتمد).
+library;
+
 import 'dart:async';
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
@@ -12,6 +27,7 @@ import '../../widgets/luxury_widgets.dart';
 import '../../widgets/socratic_dialog.dart';
 import 'package:video_player/video_player.dart';
 
+/// مشغل الفيديو السقراطي الذكي ونقاط الفحص والإرجاع العلاجي
 class SocraticVideoPlayerScreen extends StatefulWidget {
   final CurriculumLessonItemModel lesson;
   final SubjectModel? subject;