feat: Enhance documentation for BalanceBloc and BalanceService with detailed usage examples and dependencies

lib/blocs/balance/balance_bloc.dart

@@ -1,3 +1,36 @@
+/// A BLoC (Business Logic Component) that manages balance-related operations for groups.
+///
+/// This bloc handles the calculation and management of user balances within groups,
+/// including optimal settlement calculations and marking settlements as completed.
+///
+/// The bloc processes three main events:
+/// - [LoadGroupBalances]: Loads and calculates all user balances for a specific group
+/// - [RefreshBalance]: Refreshes the balance data while maintaining the current state when possible
+/// - [MarkSettlementAsCompleted]: Records a settlement transaction between users
+///
+/// Dependencies:
+/// - [BalanceRepository]: Repository for balance data operations
+/// - [BalanceService]: Service for balance calculations and settlement logic
+/// - [ErrorService]: Service for error logging and handling
+///
+/// Example usage:
+/// ```dart
+/// final balanceBloc = BalanceBloc(
+///   balanceRepository: balanceRepository,
+///   expenseRepository: expenseRepository,
+/// );
+/// 
+/// // Load balances for a group
+/// balanceBloc.add(LoadGroupBalances('groupId123'));
+/// 
+/// // Mark a settlement as completed
+/// balanceBloc.add(MarkSettlementAsCompleted(
+///   groupId: 'groupId123',
+///   fromUserId: 'user1',
+///   toUserId: 'user2',
+///   amount: 50.0,
+/// ));
+/// ```
 import 'package:flutter_bloc/flutter_bloc.dart';
 import '../../repositories/balance_repository.dart';
 import '../../repositories/expense_repository.dart';